Hi @albertcht. This isn't ready yet but I'm opening it as a draft so we can begin discussions and code reviews. The goal of this PR is to refactor Hypervel to be a fully standalone framework that is as close to 1:1 parity with Laravel as possible.

Why one large PR

Sorry about the size of this PR. I tried spreading things across multiple branches but it made my work a lot more difficult. This is effectively a framework refactor - the database package is tightly coupled to many other packages (collections, pagination, pool) as well as several support classes, so all these things need to be updated together. Splitting it across branches would mean each branch needs multiple temporary workarounds + would have failing tests until merged together, making review and CI impractical.

A single large, reviewable PR is less risky than a stack of dependent branches that can't pass CI independently.

Reasons for the refactor

1. Outdated Hyperf packages

It's been difficult to migrate existing Laravel projects to Hypervel because Hyperf's database packages are quite outdated. There are almost 100 missing methods, missing traits, it doesn't support nested transactions, there are old Laravel bugs which haven't been fixed (eg. JSON indices aren't handled correctly), coroutine safety issues (eg. model unguard(), withoutTouching()). Other packages like pagination, collections and support are outdated too. Stringable was missing a bunch of methods and traits, for example. There are just too many to PR to Hyperf at this point.

2. Faster framework development

We need to be able to move quickly and waiting for Hyperf maintainers to merge things adds a lot of friction to framework development. Decoupling means we don't need to work around things like PHP 8.4 compatibility while waiting for it to be added upstream. Hyperf's testing package uses PHPUnit 10 so we can't update to PHPUnit 13 (and Pest 4 in the skeleton) when it releases in a couple of weeks. v13 has the fix that allows RunTestsInCoroutine to work with newer PHPUnit versions. There are lots of examples like this.

3. Parity with Laravel

We need to avoid the same drift from Laravel that's happened with Hyperf since 2019. If we're not proactive with regularly merging Laravel updates every week we'll end up in the same situation. Having a 1:1 directory and code structure to Laravel whenever possible will make this much easier. Especially when using AI tools.

Most importantly, we need to make it easier for Laravel developers to use and contribute to the framework. That means following the same APIs and directory structures and only modifying code when there's a good reason to (coroutine safety, performance, type modernisation etc).

Right now the Hypervel codebase is confusing for both Laravel developers and AI tools:

• Some classes use Hyperf classes directly, some extend them, some replace them. You need to check multiple places to see what methods are available
• Some Hyperf methods have old (2019) Laravel signatures while some overridden ones have new ones
• The classes are in different locations to Laravel (eg. there's no hypervel/contracts package, the Hyperf database code is split across 3 packages, the Hyperf pagination package is hyperf/paginator and not hyperf/pagination)
• The tests dir structure and class names are different, making it hard to know what tests are missing when comparing them to Laravel's tests dir
• There are big differences in the API (eg. static::registerCallback('creating') vs static::creating())
• The mix of Hyperf ConfigProvider and Laravel ServiceProvider patterns across different packages is confusing for anyone who doesn't know Hyperf
• There are big functional differences eg. no nested database transactions

This makes it difficult for Laravel developers to port over apps and to contribute to the framework.

4. AI

The above issues mean that AI needs a lot of guidance to understand the Hypervel codebase and generate Hypervel boilerplate. A few examples:

• Models have trained extensively on Laravel code and expect things to have the same API. Generated boilerplate almost always contains incompatible Laravel-style code which means you have to constantly interrupt and guide them to the Hypervel-specific solutions.
• Models get confused when they have to check both Hypervel and Hyperf dependencies. They start by searching for files in the same locations as Laravel (eg. hypervel/contracts for contracts) and then have to spend a lot of time grepping for things to find them.
• The inheritance chain causes major problems. Models often search Hypervel classes for methods and won't remember to search the parent Hyperf classes as well.

And so on... This greatly limits the effectiveness of building Hypervel apps with AI. Unfortunately MCP docs servers and CLAUDE.md rules don't solve all these problems - LLMs aren't great at following instructions well and the sheer volume of Laravel data they've trained on means they always default to Laravel-style code. The only solution is 1:1 parity. Small improvements such as adding native type hints are fine - models can solve that kind of thing quickly from exception messages.

What changed so far

New packages

Removed Hyperf dependencies so far

• hyperf/database
• hyperf/database-pgsql
• hyperf/database-sqlite
• hyperf/db-connection
• hyperf/collection
• hyperf/stringable
• hyperf/tappable
• hyperf/macroable
• hyperf/codec

Database package

The big task was porting the database package, making it coroutine safe, implementing performance improvements like static caching and modernising the types.

• Ported from Laravel 12
• Added 50+ missing methods: whereLike, whereNot, groupLimit, rawValue, soleValue, JSON operations, etc.
• Full Schema builder parity including schema states
• Complete migration system (commands are still using Hyperf generators for now)
• Both Hyperf and Hypervel previously used global PHPStan ignores on database classes. I removed these and fixed the underlying issues - only legitimate "magic" things are ignored now.

Collections package

• Full Laravel parity across all methods
• Modernised with PHP 8.2+ native types
• Full LazyCollection support
• Proper generics for static analysis

Contracts package

• Centralised cross-cutting interfaces (like illuminate/contracts)
• Clean dependency boundaries - packages depend on contracts, not implementations
• Enables proper dependency inversion across the framework

Support package

• Removed hyperf/tappable, hyperf/stringable, hyperf/macroable, hyperf/codec dependencies
• Freshly ported Str, Env and helper classes from Laravel
• Consistent use of Hypervel\Context wrappers (will be porting hyperf/context soon)
• Fixed some existing bugs (eg. Number::useCurrency() wasn't actually setting the currency)

Coroutine safety

• withoutEvents(), withoutBroadcasting(), withoutTouching() now use Context instead of static properties
• Added UnsetContextInTaskWorkerListener to clear database context in task workers
• Added Connection::resetForPool() to prevent state leaks between coroutines
• Made DatabaseTransactionsManager coroutine-safe
• Comprehensive tests verify isolation

Benefits

1. Laravel 1:1 API parity - code from Laravel docs works directly
2. AI compatibility - AI assistants generate working Hypervel code
3. Easier contributions - Laravel devs can contribute without learning Hyperf
4. Reduced maintenance - fewer external dependencies to track and update
5. Modern PHP - native types throughout, PHP 8.2+ patterns
6. Better static analysis - proper generics and type hints
7. Coroutine safety - verified isolation with comprehensive tests

Testing status so far

• PHPStan passes at level 5
• All existing tests pass
• Coroutine isolation tests verify safety

What's left (WIP)

• Port the remaining Hyperf dependencies
• Port the full Laravel and Hyperf test suites
• Documentation updates
• Your feedback on architectural decisions

The refactor process

Hyperf's Swoole packages like pool, coroutine, context and http-server haven't changed in many years so porting these is straightforward. A lot of the code can be simplified since we don't need SWOW support. And we can still support the ecosystem by contributing any improvements we make back to Hyperf in separate PRs.

Eventually I'll refactor the bigger pieces like the container (contextual binding would be nice!) and the config system (completely drop ConfigProvider and move entirely to service providers). But those will be future PRs. For now the main refactors are the database layer, collections and support classes + the simple Hyperf packages. I'll just port the container and config packages as-is for now.

Let me know if you have any feedback, questions or suggestions. I'm happy to make any changes you want. I suggest we just work through this gradually, as an ongoing task over the next month or so. I'll continue working in this branch and ping you each time I add something new.

EDIT: New comments are getting lost in the commit history so linking them here:

Updated hypervel/context package ready for review

See: #349 (comment)

New hypervel/http-server, hypervel/http & hypervel/routing packages ready for review

See: #349 (comment)

New hypervel/container package ready for review

See: #349 (comment)

New hypervel/context, hypervel/coordinator, hypervel/coroutine, hypervel/engine, hypervel/pool& hypervel/redis packages ready for review

See: #349 (comment)

New hypervel/database package ready for review

See: #349 (comment)